---
description: Trace API for inspecting Ethereum state and transactions.
---

# `trace` Namespace

The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces.

A similar module exists (with other debug functions) with Geth-style traces ([`debug`](https://github.com/paradigmxyz/reth/blob/main/docs/vocs/docs/pages/jsonrpc/debug.mdx)).

The `trace` API gives deeper insight into transaction processing.

There are two types of methods in this API:

-   **Ad-hoc tracing APIs** for performing diagnostics on calls or transactions (historical or hypothetical).
-   **Transaction-trace filtering APIs** for getting full externality traces on any transaction executed by reth.

## Trace Format Specification

The trace API returns different types of trace data depending on the requested trace types. Understanding these formats is crucial for interpreting the results.

### TraceResults

The `TraceResults` object is returned by ad-hoc tracing methods (`trace_call`, `trace_callMany`, `trace_rawTransaction`, `trace_replayTransaction`, `trace_replayBlockTransactions`). It contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `output` | `string` | The return value of the traced call, encoded as hex |
| `stateDiff` | `object \| null` | State changes caused by the transaction (only if `stateDiff` trace type requested) |
| `trace` | `array \| null` | Array of transaction traces (only if `trace` trace type requested) |
| `vmTrace` | `object \| null` | Virtual machine execution trace (only if `vmTrace` trace type requested) |

### LocalizedTransactionTrace

Individual transaction traces in `trace_block`, `trace_filter`, `trace_get`, and `trace_transaction` methods return `LocalizedTransactionTrace` objects:

| Field | Type | Description |
|-------|------|-------------|
| `action` | `object` | The action performed by this trace |
| `result` | `object \| null` | The result of the trace execution |
| `error` | `string \| null` | Error message if the trace failed |
| `blockHash` | `string \| null` | Hash of the block containing this trace |
| `blockNumber` | `number \| null` | Number of the block containing this trace |
| `transactionHash` | `string \| null` | Hash of the transaction containing this trace |
| `transactionPosition` | `number \| null` | Position of the transaction in the block |
| `subtraces` | `number` | Number of child traces |
| `traceAddress` | `array` | Position of this trace in the call tree |
| `type` | `string` | Type of action: `"call"`, `"create"`, `"suicide"`, or `"reward"` |

### Action Types

#### Call Action (`type: "call"`)

| Field | Type | Description |
|-------|------|-------------|
| `callType` | `string` | Type of call: `"call"`, `"callcode"`, `"delegatecall"`, or `"staticcall"` |
| `from` | `string` | Address of the caller |
| `to` | `string` | Address of the callee |
| `gas` | `string` | Gas provided for the call |
| `input` | `string` | Input data for the call |
| `value` | `string` | Value transferred in the call |

#### Create Action (`type: "create"`)

| Field | Type | Description |
|-------|------|-------------|
| `from` | `string` | Address of the creator |
| `gas` | `string` | Gas provided for contract creation |
| `init` | `string` | Contract initialization code |
| `value` | `string` | Value sent to the new contract |

#### Suicide Action (`type: "suicide"`)

| Field | Type | Description |
|-------|------|-------------|
| `address` | `string` | Address of the contract being destroyed |
| `refundAddress` | `string` | Address receiving the remaining balance |
| `balance` | `string` | Balance transferred to refund address |

#### Reward Action (`type: "reward"`)

| Field | Type | Description |
|-------|------|-------------|
| `author` | `string` | Address receiving the reward |
| `value` | `string` | Amount of the reward |
| `rewardType` | `string` | Type of reward: `"block"` or `"uncle"` |

### Result Format

When a trace executes successfully, the `result` field contains:

| Field | Type | Description |
|-------|------|-------------|
| `gasUsed` | `string` | Amount of gas consumed by this trace |
| `output` | `string` | Return data from the trace execution |
| `address` | `string` | Created contract address (for create actions only) |
| `code` | `string` | Deployed contract code (for create actions only) |

### State Diff Format

When `stateDiff` trace type is requested, the `stateDiff` field contains an object mapping addresses to their state changes:

```json
{
  "0x123...": {
    "balance": {
      "*": {
        "from": "0x0",
        "to": "0x1000"
      }
    },
    "nonce": {
      "*": {
        "from": "0x0",
        "to": "0x1"
      }
    },
    "code": {
      "*": {
        "from": "0x",
        "to": "0x608060405234801561001057600080fd5b50..."
      }
    },
    "storage": {
      "0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563": {
        "*": {
          "from": "0x0",
          "to": "0x1"
        }
      }
    }
  }
}
```

### VM Trace Format

When `vmTrace` trace type is requested, the `vmTrace` field contains detailed virtual machine execution information including opcodes, stack, memory, and storage changes at each step. The exact format depends on the specific VM tracer implementation.

## Ad-hoc tracing APIs

Ad-hoc tracing APIs allow you to perform diagnostics on calls or transactions (historical or hypothetical), including:

-   Transaction traces (`trace`)
-   VM traces (`vmTrace`)
-   State difference traces (`stateDiff`)

The ad-hoc tracing APIs are:

-   [`trace_call`](#trace_call)
-   [`trace_callMany`](#trace_callmany)
-   [`trace_rawTransaction`](#trace_rawtransaction)
-   [`trace_replayBlockTransactions`](#trace_replayblocktransactions)
-   [`trace_replayTransaction`](#trace_replaytransaction)

## Transaction-trace filtering APIs

Transaction trace filtering APIs are similar to log filtering APIs in the `eth` namespace, except these allow you to search and filter based only upon address information.

Information returned includes the execution of all contract creations, destructions, and calls, together with their input data, output data, gas usage, transfer amounts and success statuses.

The transaction trace filtering APIs are:

-   [`trace_block`](#trace_block)
-   [`trace_filter`](#trace_filter)
-   [`trace_get`](#trace_get)
-   [`trace_transaction`](#trace_transaction)

## `trace_call`

Executes the given call and returns a number of possible traces for it.

The first parameter is a transaction object where the `from` field is optional and the `nonce` field is omitted.

The second parameter is an array of one or more trace types (`vmTrace`, `trace`, `stateDiff`).

The third and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`).

| Client | Method invocation                                              |
| ------ | -------------------------------------------------------------- |
| RPC    | `{"method": "trace_call", "params": [tx, trace[], block]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_call","params":[{},["trace"]]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "output": "0x",
        "stateDiff": null,
        "trace": [{
            "action": {
                "callType": "call",
                "from": "0x0000000000000000000000000000000000000000",
                "to": "0x0000000000000000000000000000000000000000",
                "gas": "0x76c0",
                "input": "0x",
                "value": "0x0"
            },
            "result": {
                "gasUsed": "0x0",
                "output": "0x"
            },
            "subtraces": 0,
            "traceAddress": [],
            "type": "call"
        }],
        "vmTrace": null
    }
}
```

## `trace_callMany`

Performs multiple call traces on top of the same block, that is, transaction `n` will be executed on top of a pending block with all `n - 1` transaction applied (and traced) first.

The first parameter is a list of call traces, where each call trace is of the form `[tx, type[]]` (see [`trace_call`](#trace_call)).

The second and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`).

| Client | Method invocation                                          |
| ------ | ---------------------------------------------------------- |
| RPC    | `{"method": "trace_callMany", "params": [[[tx, type[]], ...], block]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "output": "0x",
            "stateDiff": null,
            "trace": [{
                "action": {
                    "callType": "call",
                    "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
                    "gas": "0x1dcd12f8",
                    "input": "0x",
                    "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
                    "value": "0x186a0"
                },
                "result": {
                    "gasUsed": "0x0",
                    "output": "0x"
                },
                "subtraces": 0,
                "traceAddress": [],
                "type": "call"
            }],
            "vmTrace": null
        },
        {
            "output": "0x",
            "stateDiff": null,
            "trace": [{
                "action": {
                    "callType": "call",
                    "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
                    "gas": "0x1dcd12f8",
                    "input": "0x",
                    "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
                    "value": "0x186a0"
                },
                "result": {
                    "gasUsed": "0x0",
                    "output": "0x"
                },
                "subtraces": 0,
                "traceAddress": [],
                "type": "call"
            }],
            "vmTrace": null
        }
    ]
}
```

## `trace_rawTransaction`

Traces a call to `eth_sendRawTransaction` without making the call, returning the traces.

| Client | Method invocation                                                     |
| ------ | --------------------------------------------------------------------- |
| RPC    | `{"method": "trace_rawTransaction", "params": [raw_tx, type[]]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "output": "0x",
        "stateDiff": null,
        "trace": [{
            "action": {
                "callType": "call",
                "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
                "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",
                "gas": "0x186a0",
                "input": "0x",
                "value": "0x0"
            },
            "result": {
                "gasUsed": "0x0",
                "output": "0x"
            },
            "subtraces": 0,
            "traceAddress": [],
            "type": "call"
        }],
        "vmTrace": null
    }
}
```

## `trace_replayBlockTransactions`

Replays all transactions in a block returning the requested traces for each transaction.

| Client | Method invocation                                                        |
| ------ | ------------------------------------------------------------------------ |
| RPC    | `{"method": "trace_replayBlockTransactions", "params": [block, type[]]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_replayBlockTransactions","params":["0x2ed119",["trace"]]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "output": "0x",
            "stateDiff": null,
            "trace": [{
                "action": {
                    "callType": "call",
                    "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
                    "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",
                    "gas": "0x186a0",
                    "input": "0x",
                    "value": "0x0"
                },
                "result": {
                    "gasUsed": "0x0",
                    "output": "0x"
                },
                "subtraces": 0,
                "traceAddress": [],
                "type": "call"
            }],
            "transactionHash": "0x4e70b5d8d5dc43e0e61e4a8f1e6e4e6e4e6e4e6e4e6e4e6e4e6e4e6e4e6e4e6e4",
            "vmTrace": null
        }
    ]
}
```

## `trace_replayTransaction`

Replays a transaction, returning the traces.

| Client | Method invocation                                                    |
| ------ | -------------------------------------------------------------------- |
| RPC    | `{"method": "trace_replayTransaction", "params": [tx_hash, type[]]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_replayTransaction","params":["0x02d4a872e096445e80d05276ee756cefef7f3b376bcec14246469c0cd97dad8f",["trace"]]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "output": "0x",
        "stateDiff": null,
        "trace": [{
            "action": {
                "callType": "call",
                "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
                "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
                "gas": "0x13e99",
                "input": "0x16c72721",
                "value": "0x0"
            },
            "result": {
                "gasUsed": "0x183",
                "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
            },
            "subtraces": 0,
            "traceAddress": [],
            "type": "call"
        }],
        "vmTrace": null
    }
}
```

## `trace_block`

Returns traces created at given block.

| Client | Method invocation                              |
| ------ | ---------------------------------------------- |
| RPC    | `{"method": "trace_block", "params": [block]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_block","params":["0x2ed119"]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "action": {
                "callType": "call",
                "from": "0xaa7b131dc60b80d3cf5e59b5a21a666aa039c951",
                "gas": "0x0",
                "input": "0x",
                "to": "0xd40aba8166a212d6892125f079c33e6f5ca19814",
                "value": "0x4768d7effc3fbe"
            },
            "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
            "blockNumber": 3068185,
            "result": {
                "gasUsed": "0x0",
                "output": "0x"
            },
            "subtraces": 0,
            "traceAddress": [],
            "transactionHash": "0x07da28d752aba3b9dd7060005e554719c6205c8a3aea358599fc9b245c52f1f6",
            "transactionPosition": 0,
            "type": "call"
        }
    ]
}
```

## `trace_filter`

Returns traces matching given filter.

Filters are objects with the following properties:

-   `fromBlock`: Returns traces from the given block (a number, hash, or a tag like `latest`).
-   `toBlock`: Returns traces to the given block.
-   `fromAddress`: Sent from these addresses
-   `toAddress`: Sent to these addresses
-   `after`: The offset trace number
-   `count`: The number of traces to display in a batch

All properties are optional.

| Client | Method invocation                                |
| ------ | ------------------------------------------------ |
| RPC    | `{"method": "trace_filter", "params": [filter]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_filter","params":[{"fromBlock":"0x2ed0c4","toBlock":"0x2ed128","toAddress":["0x8bbB73BCB5d553B5A556358d27625323Fd781D37"],"after":1000,"count":100}]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "action": {
                "callType": "call",
                "from": "0x32be343b94f860124dc4fee278fdcbd38c102d88",
                "gas": "0x4c40d",
                "input": "0x",
                "to": "0x8bbb73bcb5d553b5a556358d27625323fd781d37",
                "value": "0x3f0650ec47fd240000"
            },
            "blockHash": "0x86df301bcdd8248d982dbf039f09faf792684e1aeee99d5b58b77d620008b80f",
            "blockNumber": 3068183,
            "result": {
                "gasUsed": "0x0",
                "output": "0x"
            },
            "subtraces": 0,
            "traceAddress": [],
            "transactionHash": "0x3321a7708b1083130bd78da0d62ead9f6683033231617c9d268e2c7e3fa6c104",
            "transactionPosition": 3,
            "type": "call"
        }
    ]
}
```

## `trace_get`

Returns trace at given position.

| Client | Method invocation                                        |
| ------ | -------------------------------------------------------- |
| RPC    | `{"method": "trace_get", "params": [tx_hash, indices[]]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action": {
            "callType": "call",
            "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
            "gas": "0x13e99",
            "input": "0x16c72721",
            "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
            "value": "0x0"
        },
        "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
        "blockNumber": 3068185,
        "result": {
            "gasUsed": "0x183",
            "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
        },
        "subtraces": 0,
        "traceAddress": [
            0
        ],
        "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
        "transactionPosition": 2,
        "type": "call"
    }
}
```

## `trace_transaction`

Returns all traces of given transaction

| Client | Method invocation                                      |
| ------ | ------------------------------------------------------ |
| RPC    | `{"method": "trace_transaction", "params": [tx_hash]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_transaction","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"]}
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "action": {
                "callType": "call",
                "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
                "gas": "0x13e99",
                "input": "0x16c72721",
                "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
                "value": "0x0"
            },
            "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
            "blockNumber": 3068185,
            "result": {
                "gasUsed": "0x183",
                "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
            },
            "subtraces": 0,
            "traceAddress": [
                0
            ],
            "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
            "transactionPosition": 2,
            "type": "call"
        }
    ]
}
```

## `trace_transactionOpcodeGas`

Returns opcode gas usage aggregated per opcode for a single transaction in no particular order.

| Client | Method invocation                                                     |
| ------ | --------------------------------------------------------------------- |
| RPC    | `{"method": "trace_transactionOpcodeGas", "params": [tx_hash]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_transactionOpcodeGas","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"]}
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
    "opcodeGas": [
      { "opcode": "PUSH1", "count": 10, "gasUsed": 30 },
      { "opcode": "CALL", "count": 1, "gasUsed": 700 }
    ]
  }
}
```

## `trace_blockOpcodeGas`

Returns opcode gas usage aggregated per opcode for every transaction in a block.

| Client | Method invocation                                                |
| ------ | ---------------------------------------------------------------- |
| RPC    | `{"method": "trace_blockOpcodeGas", "params": [block]}` |

### Example

```js
// > {"jsonrpc":"2.0","id":1,"method":"trace_blockOpcodeGas","params":["latest"]}
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
    "blockNumber": 3068185,
    "transactions": [
      {
        "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
        "opcodeGas": [
          { "opcode": "PUSH1", "count": 10, "gasUsed": 30 }
        ]
      }
    ]
  }
}
```
